home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Almathera Ten Pack 3: CDPD 3
/
Almathera Ten on Ten - Disc 3: CDPD3.iso
/
fish
/
726-750
/
742
/
icalc
/
docs
/
userguide
< prev
next >
Wrap
Text File
|
1995-03-18
|
38KB
|
1,123 lines
3micalc 0m1mversion 20m.1m1
0mA complex-number expression language
(C) 1991,1992 Martin W.Scott
All Rights Reserved.
User Guide
icalc User Guide icalc
1mIntroduction
0m3micalc 0mis a terminal-based calculator; the 1mi 0mstands for
1mimaginary0m, denoting the fact that the calculator works with
complex numbers. There are many calculator programs for the
Amiga, but to my knowledge, none with this ability. 3micalc
0malso performs real (normal) calculations too, and you can
completely ignore the complex number facility if you wish.
Version 2.0 of icalc introduced major additions, effectively
making 3micalc 0ma C-like programming language. However, you
can completely ignore these extensions if you shy away from
programming. In light of this, the more advanced
documentation is kept separate from the simple instructions,
in the 'Advanced Guide', which covers such topics as
number-bases, programming constructs, arrays and scripts.
1mComplex Numbers
0mA complex number is made up of two components: a real part,
and an imaginary part. The imaginary part is just a real
number multiplied by the special number i, which is defined
to be the square root of -1. Thus, i*i = -1. This may all
seem very artificial, but it's not; complex numbers exist as
surely as real numbers do (or don't, depending on your
mathematical philosophy). However, real numbers seem more
tangible to us, since we use them (or approximations to
them) in our everyday life. It is not the purpose of this
guide to teach you anything about complex numbers - if you
don't know about them, you probably don't need to, but if
you do any numerical work, you will probably still find
3micalc 0museful, because real numbers are a subset of complex
numbers, and can thus be manipulated by this program as in
an ordinary calculator-type program. Don't be put off - I
hardly ever need to use complex numbers - I just like the
facility to be there for the odd occasion when I do use
them.
In what follows, examples are indented. Things you type are
preceded by a '>' prompt sign, and output from 3micalc 0mis
further indented.
1mExpressions
0m3micalc 0maccepts expressions in the usual form for computer
expressions, i.e. multiplication must be explicitly shown
by '*', and function arguments enclosed within parentheses.
The exception to this is the method of inputing imaginary
parts of complex numbers. If you want to enter the number 3
+ 4i, you can type either
> 3+4i
or
> 3+4*i
icalc -2- version 2.1
icalc User Guide icalc
but 3mnot
0m> 3+i4 # this won't do...
since this would give an ambiguous grammar - is it i*4 or
the variable "i4"?
In almost all circumstances, the algebraic "4i" is
preferred, but there is one exception, exponentation "^". If
you want 3*i^3, you must type
> 3*i^3
and not
> 3i^3
The former gives the correct result, -3i, whilst the latter
gives -27i. This is because the grammar sees "3i" as a
number in its own right, and not an implicit
multiplication.
NB: Implicit multiplication (leaving out '*' sign) is only
recognised in the case of a numerical multiple of i.
See the appendices for the complete list of commands,
operators, constants and builtin functions that 3micalc
0msupports.
Expressions are separated by newlines or semi-colons ';'.
You may also split an expression over multiple lines using a
backslash '\' to indicate continuation to the next input
line. Comments are introduced by '#', and the rest of the
input line is ignored. You may also place comments after
backslashes.
1mSample Expressions
0mBelow are a few examples of what 3micalc 0mwill accept.
> x=4 # an assignment statement
assigns to variable x the value 4.
> # and now, two statements separated by a semi-colon
> sqr(x); x*sqr(x);
displays the values 16 and 64 (sqr(x) returns x*x). The
next example demonstrates a problem inherent in machine
calculations:
> 2*sin(x)*cos(x) - sin(2*x)
displays the value -2.22044604925e-16. The answer should be
0, and indeed is very close to that. The inaccuracy results
because each term has a value as close to the actual value
icalc -3- version 2.1
icalc User Guide icalc
as the computer's internal representation of numbers can
hold (see the Advanced Guide for a small discussion of this
particular case).
You can change the number of significant figures 3micalc
0mdisplays by the prec() function - see Appendix 4.
1mStarting icalc
0m3micalc 0mmay be started from either the CLI or Workbench. Once
started, 3micalc 0mwill process the file whose name is contained
in the environment variable ICALCINIT, defaulting to the
file "s:icalc.init" if no environment variable is declared.
This initialization file may be used to extend the functions
available in 3micalc. 0mA sample file is given in the S
directory of this distribution. If running under AmigaDOS
1.3, it is recommended that you use NEWCON: or ConMan to
provide editing and history facilities. For users of
AmigaDOS 2.0, the normal CON: window has these facilities
built-in, and you may also add a close gadget.
CLI Usage
The synopsis for icalc is
icalc [file-list]
where file-list is a list of input files. 3micalc 0mwill read
(process) the files in the list and exit. If a file-list is
specified, 3micalc 0mwill assume that you do not wish to use the
program interactively. If you do, you should specify one of
the files as a dash "-"; this is taken to mean "use standard
input". If no file-list is given, 3micalc 0mstarts an
interactive session. You can obviously redirect output to a
file if you wish (and redirect input from a file, but this
is generally unnecessary). For example, if you wanted to
use definitions contained in a file called "stat.ic", and
then type some expressions in at the terminal, you would use
icalc stat.ic -
to start the program. Because the program makes extensive
use of recursion, I recommend you use a stack size of about
20K when running 3micalc.
0mWorkbench Usage
To start 3micalc 0mfrom the Workbench, simply double-click its
icon. You may also pass arguments (definition/command
files) to 3micalc 0min the usual Workbench manner (shift-select
etc.). 3micalc 0mwill then open a window on the Workbench
screen for an interactive session. You can specify the
window to be opened by modifying the WINDOW tooltype (click
once on the 3micalc 0micon, and select "Info" from the Workbench
menu). By default, this is a CON: window. (As noted above,
AmigaDOS 1.3 users could alter this to a NEWCON: window).
icalc -4- version 2.1
icalc User Guide icalc
You may also set the default tool of a definition file's
project icon to be 3micalc. 0mThen simply double clicking the
project icon will launch 3micalc 0mand read the definition
file. Remember, however, to set the project icon's stack to
20000, or you may get a stack overflow error.
Exiting icalc
To end an interactive session of 3micalc 0m(from either CLI or
Workbench) use the command "quit" or "exit". You can also
type ^\ (press the control key and '\' simultaneously). If
running under AmigaDOS 2.0, you can use the window's
close-gadget.
1mVariables
0mVariables in 3micalc 0mcan be named arbitrarily, as long as no
name conflicts with a pre-defined symbol name, such as sin
or PI. The standard conventions apply: the first character
must be a letter or underscore, followed by a string of
letters, digits and underscores. Case IS significant.
Variables are introduced by using them; If a variable is
used before it has been initialized (i.e. has had a value
assigned to it), 3micalc 0mwill warn the user and use the value
zero. Assignments can appear anywhere in an expression, and
are in fact expressions in their own right (as in the
programming language C). So, you can do things like
> apple = banana = apricot = 34
to assign the value 34 to all these variables. Since
assignments are expressions, their value being the
assignment value, you can also do
> apple = sqr(banana = 12)
which assigns the value 12 to "banana", and 144 to "apple".
You can of course assign new values to existing variables.
1mConstants and ans
0m3micalc 0mcomes with several predefined constants, e.g. PI,
GAMMA etc, which by convention are all in upper-case. You
cannot assign a new value to a constant. There is a special
constant, "ans", which isn't really a constant at all, but
is made so to prevent assignments to it. "ans" contains the
value of the previously evaluated expression, and so is
useful when splitting a calculation up into smaller chunks.
> 1 + 2 + 3
6
> ans * 12
72
You can also use it for recursive formulas. For example,
icalc -5- version 2.1
icalc User Guide icalc
the logistic equation xnext = rx(1-x) for parameter r = 3.5,
initial x = 0.4 could be iterated as follows:
> r = 3.5; 0.4 # initialize r and ans
3.5
0.4
> r*ans*(1-ans)
0.84
> r*ans*(1-ans)
0.4704
> r*ans*(1-ans)
0.87193344
> r*ans*(1-ans)
0.39082930673
and so on. Of course, you needn't use "ans" here; you could
just use assignments to "x", but it illustrates the point.
Note that once the necessary variables have been
initialised, the same expression is evaluated repeatedly.
Thus, if you are using a window with history capabilities
you can save a lot of typing by pressing the up-arrow.
There are other ways to perform repeated calculations in
3micalc. 0mYou can use so-called Special functions (explained
below), or the C-style looping constructs described in the
'Advanced Guide'.
1mBuiltin Functions
0m3micalc 0mcomes with many builtin functions, for example sin,
cos, sqrt, exp, ln etc. There are some special functions
for complex numbers too, namely Im, Re, arg, norm. All
functions take real or complex arguments, which can be any
expression, although in some cases, the complex part is
discarded. Consider
> sin(12-3i)
-5.40203477452 - 8.45362341558 i
> asin(ans)
-0.56637061436 - 3 i
> sin(ans)
-5.40203477452 - 8.45362341558 i
Here we see a property of inverse trigonometric functions,
their many-valuedness, due to their periodicity on the real
line. The function asin returns a value in its PVR
(principal value range) as do all many-valued functions in
3micalc. 0mSee the 'Advanced Guide' for exact definitions of
PVRs of the inverse trigonometric functions used in 3micalc.
0mOther functions owe their many-valuedness to the fact that
the argument of a complex number is 2*PI-periodic. In 3micalc
0mthe argument always falls in the range -PI < arg <= PI.
Another thing to bear in mind if you're not using complex
numbers is that expressions like
icalc -6- version 2.1
icalc User Guide icalc
> ln(-1)
return a value, 3.14159265359*i (PI*i) in this case. (The
natural logarithm onto the real line is defined for range
(0, +infinity)).
1mUser0m-1mdefined Functions
0mUser-defined functions give 3micalc 0mits flexibility and
power. Any function that can be stated as a normal
expression (or list of expressions) may easily be defined
and used like a builtin function. In this document, only
very simple function definitions are explained. Functions
more akin to those in a computer program are described in
the 'Advanced Guide'.
Functions are defined using the 'func' keyword, in the
following manner:
func <name> ( <parameter-list> ) = <expr>
so to define the function f(z) = sin(sqrt(z)), simply type
> func f(z) = sin(sqrt(z))
Note that z is 3mlocal 0mto the function, not a global
variable. Thus, if z has been defined as a variable before
defining f(z), it is unaltered when you call f(z). The
standard initiation file 'icalc.init' contains many simple
function definitions, and you may find it instructive to
examine it.
Multi-parameter functions may also be defined. For example,
the volume of a right-circular cone is given by the formula
volume = 1/3*PI*sqr(r)*h
where r is the radius of the base, and h is the height of
the cone. We can define a function to compute the volume as
follows:
> func conevol(r,h) = 1/3*PI*sqr(r)*h
> conevol(1,3)
3.14159265359
It is also possible (though of limited use) to declare
functions that take no parameters. Examples of
multi-parameter functions are given in the sample definition
files.
NB: As with most programming languages, don't write circular
definitions; 3micalc 0mdoes not detect them, and will swiftly
run out of stack space.
icalc -7- version 2.1
icalc User Guide icalc
1mSpecial Functions
0mCertain builtin functions in 3micalc 0mare called 3mspecial
0mbecause of the way they use their arguments. Normally, when
you `call' a function, its arguments are first evaluated and
then the function is called. With special functions
however, the arguments are not evaluated; this means that
the expressions themselves (and not just their values) can
be used by the function in a number of ways.
Special functions were introduced in version 1.1 of 3micalc.
0mbut since version 2.0, they have become largely redundant
(with one or two exceptions) due to the C-style programming
constructs added. However, for non-programmers or people
who don't wish to use 3micalc 0mas a programming language, they
do provide a means for performing several common operations
which would otherwise prove difficult.
Some special functions take integers as arguments; if you
supply an expression with a non-integral value, this value
will be stripped of its imaginary component, and the
remaining real number rounded to the nearest integer.
Currently, the special functions are as follows.
Sum(var,upto,expr)
This command calculates finite sums. The variable `var' is
the index of summation, with an optional assignment. While
the value of the index is less than or equal to the value of
the upto argument, the value of expr is added to an internal
summation variable, which is initially zero. Examples will
help to clarify usage.
To evaluate the sum of the first 100 natural numbers
(naively) we could do
> Sum(n=1,100,n)
which gives the answer as 5050 (which is 100/2*(100+1)).
Note the initial assignment of 1 to n. If no initial value
is specified, a value of zero is assumed (and the user is
notified of this). When a summation is complete, the index
variable holds a value 1 greater than the value of upto. We
can also use Sum() to provide approximations to infinite
sums.
> Sum(n=1, 100, 1/sqr(n))
1.63498390018
Using the fact that n will now hold the value 101, we can
continue the summation to 200 by the following:
> ans + Sum(n, n+99, 1/sqr(n))
1.63994654601
and continue to obtain closer answers by repeating the last
line,
icalc -8- version 2.1
icalc User Guide icalc
> ans + Sum(n, n+99, 1/sqr(n))
1.6416062829
which is getting there (the infinite series sums to PI^2/6 =
1.64493406685). One last example, to evaluate the sum of
the all even numbers upto 100.
> Sum(n=1, 50, 2*n)
2550
Prod(var,upto,expr)
This command calculates finite products, in an analogous way
to the Sum() special function. Examples will demonstrate
its use.
> Prod(n=1, 10, n)
calculates 10!, which is 3628800. We can also use Prod() to
investigate infinite products, although care should be
taken. Consider Wallis's product for PI/2:
PI 2×2×4×4×6×6×...
-- = ---------------
2 1×3×3×5×5×7×...
Here the product is 2/1 * 2/3 * 4/3 * 4/5 * ... and so we
must find a method of producing the numerators and
denominators from an index. It is easiest to evaluate the
product in pairs of terms. Thus, for each term our
numerator will be sqr(2*n), and our denominator will be
(2*n-1)*(2*n+1) = sqr(2*n)-1. Note that sqr(2*n) appears in
both the numerator and denominator. We can therefore
optimise the calculation by using a temporary variable to
hold this value. We proceed as follows:
> Prod(n=1, 100, (t = sqr(2*n))/(t-1))
1.56689374531
> ans * Prod(n, n+99, (t = sqr(2*n))/(t-1))
1.56883895048
> ans * Prod(n, n+99, (t = sqr(2*n))/(t-1))
1.56949005194
every(var,upto,expr) and vevery(var,upto,expr)
These functions preform more general iterations than Sum()
and Prod(). They return the value of the last expression
evaluated, ie. expr evaluated when var = upto. The
difference between every() and vevery() is that the latter
produces verbose output - it prints the value of the index
and the result of the expression for every iteration.
Example: evaluate sin(sin(...(sin(z))...)) with sin()
applied 10 times. Here we'll take z to be 1-i.
> last = 1-i; every(n=1, 10, last = sin(last))
icalc -9- version 2.1
icalc User Guide icalc
0.51856951608 - 0.01039404248 i
Although every() and vevery() are useful in some situations,
most iterations are more easily performed by using Sum() and
Prod().
multi(expr1, expr2, ... , exprN)
This special function still exists for upward compatability,
but it is syntactically equivalent to the C-style block
introduced with version 2.0:
{ expr1 ; expr2 ; ... ; exprN; }
(In fact, the semicolons can be omitted and new-lines used
instead - see the 'Advanced Guide').
The value of a call to multi or a block expression is that
of the last expression evaluated, namely exprN. If output
has not been switched off with the 'silent' command, use of
a block will print the result of it's last argument. In
order to print the results of other expressions, the builtin
function print() is supplied. print() takes one argument,
prints it to the display, and returns its argument as a
result. In this way, expressions can appear to return more
than one result.
An example: write a function that converts Cartesian
coordinates into polar form, returning the radius and angle
in degrees, and setting the variables r and theta to these
values.
> func rec2pol(x,y) = {
> r=print(sqrt(x*x+y*y))
> theta=DEG*arg(x+i*y)
> }
> rec2pol(3,4)
5
53.1301023542
Note the use of complex argument to obtain the correct
quadrant.
1mOther features
0m3micalc 0mnow has a full complement of common programming
constructs (C-style) such as if-else, for-loops etc. This
necessitated the addition of relational operators >=, >
etc. and logical operators &&, ! etc.
In order to make the range of applications wider,
single-dimensional arrays may also be used in a very simple
manner.
icalc -10- version 2.1
icalc User Guide icalc
User-function arguments may be arrays, pointers to variables
and even expressions (in the sense of expressions to
'special' functions) although in this area, syntax differs
considerably from the C programming language.
All these and other extensions are very useful facilities,
but non-essential for simple work. They are described in
detail in the 'Advanced Guide'.
1mCommands
0m3micalc 0mhas a few commands to make life easier. One or two
commands take a string as an argument. Strings are enclosed
in double-quotes, e.g. "hello", although you may drop the
trailing quote if you wish. It should be noted that
commands may NOT be used within function or block
declarations.
bye
quit
exit
not surprisingly, these commands terminate 3micalc.
0msilent
stops generation of any further output. However, errors and
warnings are still displayed. It is useful for
initialization files containing lots of definitions.
verbose
restores generation of output.
help
reminds you what other commands are available.
vars
lists all currently defined variables and their values, and
allocated arrays.
consts
lists all predefined constants and their values.
builtins
lists all built-in functions available, including special
functions.
functions
lists all user-defined functions, with their parameter
lists.
echo <string>
simply prints given string (like Shell echo command).
pwd
prints the current directory of 3micalc.
0mcd <new-directory>
changes current directory of 3micalc. 0mEg. cd "s:"
icalc -11- version 2.1
icalc User Guide icalc
exec <command-string>
executes command as if it had been typed in a Shell. Eg.
exec "ed s:icalc.init". If 3micalc 0mis started from the
Workbench, output from exec'd commands will only be
displayed if you are using AmigaDos 2.0 or above (this is a
compiler/OS bug).
read <file>
reads and evaluates contents of named file (in same manner
as if passed on command-line to 3micalc 0mor as a Workbench
argument.
writevars <file>
dumps all variables defined in current session (including
arrays) to specified file, for subsequent restoration with
the read command at another session. At present
user-function definitions are NOT saved (and are never
likely to be in future versions). The file is in
human-readable form.
There are a couple of other commands detailed in the
'Advanced Guide'.
1mBugs
0mOne major bug was fixed in release 1.1a - the sqrt() builtin
was not returning values in the correct quadrant.
Consequently, the inverse trigonometric functions, which are
defined using sqrt(), broke. This has now been corrected.
Thanks to Pierre Ardichvili for pointing this out. (Version
1.1a fixed this bug, but wasn't widely distributed because
version 2.0 was (supposedly) imminent.)
From version 2.1, new routines were written to replace the
ones supplied with the SAS/C compiler (specifically the
scanf and printf "%g" routines) thus removing all bugs
associated with these routines (such as printing "0." and
"-0." amongst others). Thanks to Eric Rankin for reporting
the display bugs.
I hope that's all the major bugs ironed out, but there may
be the odd little bug in there somewhere -- if you find any,
PLEASE let me know and I'll try to fix them.
If there's something you hate about 3micalc 0mand would like
changed, or something you'd love that's not in, drop me a
line (at the address below), or email me.
1mSource
0m3micalc 0mwas written in C, and compiled with SAS/C (version
5.10a). Berkeley Yacc was used to generate the parser. The
source to version 2.1 of 3micalc 0mis available on request, for
a small fee. See the 'ReadMe.First' document for further
details.
icalc -12- version 2.1
icalc User Guide icalc
1mCredits
0mThanks to the authors of Berkeley Yacc (it makes these
things so much easier to write and modify) and to SAS for a
(fairly) stable C compiler.
Thanks also to Steve Koren for Sksh, and Mike Meyer et al
for Mg3; together they make a great development
environment.
Jeremy McDonald provided me with a routine for displaying
numbers in any base (from 2 to 36) which has been used as
the core of the number-displaying routine used in 3micalc 0m--
thanks Jeremy!
Many of the algorithms used in the sample script-files that
come with 3micalc 0mwere based on those in "Numerical Recipes in
C", by Press et al. The book is very readable, and well
worth obtaining if you use numerical algorithms in your
work.
This was my first yacc-based project, and I learnt a lot
from "The Unix Programming Environment" by Brian Kernighan
and Rob Pike. Their "hoc" taught me a lot about using Yacc.
Most of all, thanks to those people who have written to me
regarding icalc, for their comments and contributions.
1mDistribution
0m3micalc 0mis freeware, copyrighted software. This copyright
applies to all files in the 3micalc 0mdistribution. You are
permitted to distribute it at only a nominal charge to cover
costs. All files should be included unmodified. Under no
circumstances should 3micalc 0mbe sold for profit.
1mThe Bottom Line
0mAlthough 3micalc 0mis not shareware, contributions would be most
welcome, as I'm a poor student, and have put a lot of work
into this project. But they're NOT required - bug reports,
praise, suggestions, neat programs etc. are welcome (and
indeed encouraged) with or without contribution. Thanks to
those kind people (small in number) who have written to me.
I can be contacted via snail mail at:
Martin W. Scott,
23 Drum Brae North,
Edinburgh, EH4 8AT
United Kingdom.
or you can email me; my address is mws@castle.ed.ac.uk
Thanks for reading this far. The appendices follow; some
details in them will not have been covered in this document,
icalc -13- version 2.1
icalc User Guide icalc
but are explained in the 'Advanced Guide'.
icalc -14- version 2.1
icalc User Guide icalc
1mAppendix 1 0m- 1mOperators 0m(1min increasing order of precedence0m)
= += -= *= /= assignment
?: ternary operator
|| logical or
&& logical and
== != equal, not equal
> >= < <= greater-than etc.
+ - addition, subtraction
* / multiplication, division
- ! unary minus, logical not
^ exponentation
' conjugate operator
1mAppendix 2 0m- 1mConstants
0mABASE index of first element for arrays
DEG Number of degrees in one radian
E exp(1)
FALSE 0
GAMMA Euler's constant, 0.57721566...
INFINITY (almost) the largest real number possible
LOG10 ln(10)
LOG2 ln(2)
PHI Golden ratio 1.61803398...
PI 4*atan(1) (that's one definition)
TRUE 1
1mAppendix 3 0m- 1mKeywords
0mfunc function declaration
array (external) array definition
local local variable definition
return return from function
if-else control-flow constructs
while-do
do-while
for
icalc -15- version 2.1
icalc User Guide icalc
1mAppendix 4 0m- 1mBuiltin functions
0mParameters are evaluated from left to write.
Parameters shown:
z implies complex number expected,
x implies real number expected,
n implies integer expected.
a implies array identifier expected.
Conversions will be made if required.
Functions you think missing below may well be defined in one of
the support scripts.
1mSingle0m-1margument functions0m:
sin(z) trigonometric functions
cos(z)
tan(z)
asin(z) inverse trigonometric functions
acos(z)
atan(z)
sinh(z) hyperbolic trigonometric functions
cosh(z)
tanh(z)
exp(z) exponential function
ln(z) natural logarithm
sqr(z) square
sqrt(z) square root
conj(z) conjugate (see also ' operator)
abs(z) absolute value (sqrt(norm(z))
norm(z) not really norm; if z=x+iy, norm(z) = x²+y²
arg(z) principal argument (in (-PI,PI])
Re(z) real part of complex number
Im(z) imaginary part of complex number
ceil(x) ceil of real part (eg. ceil(1.2) = 2)
floor(x) floor of real part (eg. floor(1.2) = 1)
int(x) return real part rounded to nearest integer
sgn(x) sign of real part (eg. sgn(-1.6) = -1)
time(x) system time in seconds, less its argument
print(z) prints and returns value of its argument
prec(n) adjust number of significant figures displayed
sigzeros(n) set # of leading zeros considered significant
error(n) abort evaluation with error n
outbase(n) print numbers using base-n
icalc -16- version 2.1
icalc User Guide icalc
1mArray functions0m:
display(a) display contents of an array
sizeof(a) returns number of elements in array
resize(a,n) changes dimension of array to new size n
arraybase(n) change first index of arrays to n
(returns old base)
1mSpecial functions0m:
Sum calculate a finite sum
Prod calculate a finite product
every perform a general iteration quietly
vevery perform a general iteration verbosely
multi evaluate many expressions (defunct)
min returns minimum real part in parameters
max returns maximum real part in parameters
min and max take an arbitrary number of arguments.
icalc -17- version 2.1